KEYROW

Syntax: KEYROW (row)
Location: QL ROM

This function is used to read the keyboard. It is not linked with a channel which means that it can be used by a job to read the keyboard whether or not that job has an active cursor.

The main advantage which this function has when compared to INKEY$ is that it allows programs to recognise when the user is pressing several keys at once, such as the left and up cursor keys to move diagonally.

The function KEYROW is able to read several keys at once by using a keyboard matrix, where each row is numbered and each key is assigned to a certain row. If that key is pressed, then a bit is set in the integer value of that row to represent which key has been pressed. 

For British QLs, the format of the matrix is:   

Row 0   |   7     4   F5   F3  F2   5  F1   F4
 Row 1  |      SPACE  \      ESC        ENTER
 Row 2  |   "     M    `    B   C   .   Z   ]
 Row 3  |   ;     G    =    F   S   K C/LCK [
 Row 4  |   J     D    P    A   1   H   3   L
 Row 5  |   O     Y    -    R  TAB  I   W   9
 Row 6  |   U     T    0    E   Q   6   2   8
 Row 7  |   ,     N    /    V   X  ALT CTRL SHIFT
------------------------------------------------------------
    bits    7     6    5    4   3   2   1   0
  (value) (128) (64) (32) (16) (8) (4) (2) (1)

Unfortunately, only one row at a time can be read with KEYROW and so the keys are arranged into groups - for example, all of the cursor keys appear on one row, as do all of the function keys. When the function is used, the supplied parameter row specifies which row of the matrix is to be looked at. The value returned will have bits set representing which keys (if any) in that row were being pressed.

ST/QL NOTES:
On the ST/QL Emulator, the KEYROW table is much extended, with the following rows being added, both to take account of the additional keys available on an ST keyboard and also to take account of the numeric keypad (hence the repetition of various keys!):   

  Row 8  | F10   F9   F8   F7  F6    BKSPCE ~
  Row 9  |        +         -     HOME
  Row 10 |                         DEL INS
  Row 11 |  <
  Row 12 |  8     7    *    /   )   ( HELP UNDO
  Row 13 |  0     3    2    1   6   5   4   9
  Row 14 |                            ENTER .
------------------------------------------------------------
     bits   7     6    5    4   3   2   1   0
  (value) (128) (64) (32) (16) (8) (4) (2) (1)

CROSS-REFERENCE:
INKEY$ and INPUT allow user input from the keyboard whilst retaining compatibility across the various QDOS implementations.  These commands are also job specific, and hence much better for use in multitasking programs.

Some of the HOT_... commands and EXEP allow you to pass a U option to the program to force the computer to freeze all other programs whilst this one is running - this can be used to ensure that a program which uses KEYROW does not carry on reading the keyboard whilst you are using another program.
